Setup Guide

This guide provides instructions for setting up and running the MyTravel application on your local development environment.

Prerequisites

The following software must be installed on your machine before proceeding with the setup:

• .NET 10 SDK - The backend is built on ASP.NET Core 10. Download from dotnet.microsoft.com
• Node.js (v18 or higher) - Required for the frontend build tools. Download from nodejs.org
• npm - Comes bundled with Node.js and is used for managing frontend dependencies

To verify your installations, run the following commands in your terminal:

dotnet --version    # Should output 10.x.x
node --version      # Should output v18.x.x or higher
npm --version       # Should output 9.x.x or higher

Installation

1. Install Frontend Dependencies

Navigate to the client project and install the required npm packages:

cd mytravel.client
npm install
cd ..

2. Configure the Backend (Optional)

The application comes with default configuration settings that work out of the box for local development. The configuration files are located in the MyTravel.Server directory:

• appsettings.json - Base configuration
• appsettings.Development.json - Development-specific settings

The default admin credentials are configured in appsettings.json:

{
  "AdminCredentials": {
    "Email": "admin@mytravel.com",
    "Password": "Admin@123!"
  }
}

For production deployments, these credentials should be changed and stored securely using environment variables or a secrets manager.

Running the Application

The MyTravel solution uses the ASP.NET Core SPA Proxy feature, which means the frontend development server starts automatically when you run the backend. This provides a seamless development experience where both the API and client are available from a single command.

Using Visual Studio

1. Open MyTravel.slnx in Visual Studio
2. Set MyTravel.Server as the startup project
3. Press F5 to run with debugging, or Ctrl+F5 to run without debugging

Visual Studio will automatically start both the backend server and the frontend development server.

Using the Command Line

Navigate to the server project directory and run:

cd MyTravel.Server
dotnet run

For a more interactive development experience, use dotnet watch which provides hot reload capabilities. This automatically rebuilds and restarts the application when code changes are detected:

cd MyTravel.Server
dotnet watch

The dotnet watch command is recommended during active development as it significantly speeds up the feedback loop when making changes to the backend code.

Accessing the Application

Once the application is running, you can access it at the following URLs:

The frontend development server proxies API requests to the backend, so you can interact with the application entirely through the frontend URL during development.

Database

MyTravel uses SQLite as its database, which requires no additional setup. The database file is created automatically when the application first runs and is stored in the MyTravel.Server directory as mytravel.db.

The database is seeded with sample data on first run, including:

• Sample destinations and activities
• Demo blog posts
• The admin user account

To reset the database, simply delete the mytravel.db file and restart the application.

Troubleshooting

Port Already in Use

If you encounter an error indicating that a port is already in use, another application may be using ports 5083 or 49764. You can either stop the conflicting application or modify the ports in the following files:

• MyTravel.Server/Properties/launchSettings.json - Backend port configuration
• mytravel.client/vite.config.ts - Frontend port configuration

Frontend Not Starting Automatically

If the frontend does not start automatically with the backend, you can run it manually in a separate terminal:

cd mytravel.client
npm run dev

Certificate Errors

The development server uses HTTPS with a self-signed certificate. If your browser shows a certificate warning, you can proceed by accepting the risk (for development purposes only) or trust the .NET development certificate:

dotnet dev-certs https --trust

Features

This document provides a comprehensive overview of all pages and features available in the MyTravel application. The platform is divided into two main sections: the public-facing website for travelers and the administrative dashboard for platform management.

Public Pages

Homepage

Route: /

“Explore the World with Ease”

The homepage serves as the main entry point for visitors and establishes the MyTravel brand identity. A prominent hero section displays the website’s name alongside a captivating tagline that invites users to begin their travel journey. The hero includes a search interface that allows users to quickly find destinations by location or keyword.

Below the hero, the page highlights top travel destinations with visually appealing cards showcasing popular locations. A testimonials section features reviews from satisfied travelers, building trust with new visitors. Promotional offers and seasonal deals are prominently displayed to encourage immediate engagement. A clear call-to-action button labeled “Plan Your Trip Now!” guides users toward the booking flow.

Screenshots

Hero Section	Featured Destinations
Hero with tagline and search	Top destination cards

Testimonials	Call to Action Card
User reviews and ratings	Call to Action Card

User Registration and Login

Routes: /login, /register

“Create an account to access personalized travel deals.”

The authentication system provides secure access to personalized features and booking capabilities. The registration form collects essential information including email address, first name, last name, and password with confirmation. Form validation is handled client-side using react-hook-form integrated with Zod schemas, providing immediate feedback on input errors.

The login form accepts email and password credentials with options for password visibility toggle. Account verification is supported through email confirmation to ensure valid user accounts. A forgot password feature allows users to reset their credentials by receiving a password reset link via email. User sessions are managed through ASP.NET Core Identity with secure cookie-based authentication.

Features:

• Email-based registration with validation
• Account verification via email confirmation
• Forgot password functionality with email reset
• Secure session management
• Protected route redirection after login

Screenshots

Login Form	Registration Form
Email and password login	New account creation

Password Recovery	Form Validation
Password reset request	Real-time validation feedback

Destination Browsing Page

Route: /destinations

“Discover hidden gems across the world.”

The destinations page presents a comprehensive catalog of all available travel locations with rich visual content. Each destination is displayed as a card featuring high-quality images, descriptive text highlighting key attractions, and aggregated user reviews. Pricing information shows the starting cost to help users quickly assess options within their budget.

The page offers robust filtering capabilities to help users find their ideal destination. Filters are available for continent selection, activity type (beaches, hiking, cultural experiences, adventure sports), and budget range. Users can toggle between a traditional grid view for browsing and an interactive map view powered by Leaflet for geographical exploration. The search functionality allows users to find specific destinations by name or keyword.

Filter Options:

• Continent/Region selection
• Activity type (beaches, hiking, cultural, adventure)
• Budget range (economy, mid-range, luxury)
• Rating and review scores
• Seasonal availability

Screenshots

Grid View	Map View
Card-based destination browsing	Interactive Leaflet map view

Filter Panel	Search Results
Continent, activity, and budget filters	Filtered destination results

Destination Details

Route: /destinations/:id

Individual destination pages provide in-depth information about a specific location. The page opens with a gallery of high-quality images showcasing the destination’s highlights. Detailed descriptions cover the location’s history, culture, climate, and best times to visit.

Available activities are listed with descriptions and pricing, allowing users to plan their experiences. Accommodation options range from budget-friendly to luxury establishments. Users can add flights, hotels, or guided tours to their cart directly from this page, streamlining the booking process.

Screenshots

Image Gallery	Description
High-quality destination images	Details

Available Activities and Map
Tours and experiences

Itinerary Planner

Route: /planner

“Plan your dream trip effortlessly.”

The itinerary planner is an interactive tool that empowers authenticated (registered) users to create custom travel itineraries tailored to their preferences. The interface enables users to select places, accommodations, and activities, then organize them into a coherent travel plan.

The drag-and-drop functionality, powered by the dnd-kit library, allows users to easily arrange activities across different days of their trip. Users can reorder items, move activities between days, and visualize their complete journey timeline. The planner calculates estimated travel times between locations and provides running cost totals as items are added or removed.

Features:

• Drag-and-drop itinerary creation
• Day-by-day activity organization
• Estimated travel time calculations
• Running cost totals and budget tracking
• Export PDF

Screenshots

Planner Page	Adding Activities
Planner Header	Selecting activities to add

Itinerary
Activities

Booking System

Routes: /booking/:id, /checkout

“Book everything you need for your trip in one place.”

The booking system provides a unified interface for reserving all travel services. The booking page presents detailed forms for configuring reservations, including travel dates, number of travelers, and specific options such as room types, flight classes, or tour packages. Real-time availability checking ensures users only see bookable options.

The checkout page consolidates all items from the user’s cart into a comprehensive order summary. An itemized breakdown displays each service with its details and pricing. The system calculates total costs including any applicable taxes and fees. Customer information collection includes contact details and any special requirements.

Payment processing is handled securely with real-time confirmation. Upon successful payment, users receive immediate booking confirmation displayed on screen and sent via email. The confirmation includes booking reference numbers, detailed itinerary information, and relevant contact details for each service provider.

Features:

• Integrated booking for flights, hotels, and tours
• Real-time availability and pricing
• Secure payment processing
• Instant booking confirmation
• Email confirmation with booking details
• Booking reference numbers for each service

Screenshots

Booking Form	Date Selection
Service configuration options	Travel date selection

Cart Summary	Checkout Page
Itemized booking summary	Customer information entry

Payment Processing	Confirmation
Secure payment form	Booking success with reference

Interactive Map Integration

The application integrates interactive mapping capabilities using the Leaflet library with React-Leaflet bindings. Maps are featured prominently on the destinations browsing page, allowing users to explore travel locations geographically.

“Explore destinations and travel routes on an interactive map.”

Users can pan and zoom across the world map, with destination markers indicating available locations. Clicking a marker reveals a popup with destination summary information and a link to the full details page. The map view provides an intuitive way to discover destinations by region and understand geographical relationships between locations.

On individual destination pages, maps display the specific location along with nearby points of interest, helping users understand the area and plan local exploration.

Screenshots

World Map View
Global destination overview

Marker Popup	Destination Map
Quick destination info	Detailed location view

Travel Blog

Routes: /blog, /blog/:slug, /blog/new, /blog/edit/:slug

“Get inspired by amazing travel experiences.”

The blog section serves as a community-driven content hub where users can read and contribute travel stories, tips, and destination guides. The main blog page displays posts in a paginated list with preview cards showing titles, excerpts, featured images, and publication dates.

Content is organized into categories to help readers find relevant articles. Categories include solo travel adventures, family trip planning, luxury travel experiences, budget backpacking, cultural immersion, and adventure activities. Users can browse all posts or filter by their preferred category.

Individual blog posts are rendered with full rich text content using the Lexical editor’s read mode. Articles support formatted text, headings, embedded images, and other media elements. Related posts are suggested at the bottom of each article to encourage continued exploration.

Authenticated users can contribute their own travel stories through the blog editor. The editor provides a rich text interface supporting formatted content, image uploads, and category selection. Authors can save drafts, preview their work, and publish when ready to share with the community.

Content Categories:

• Solo travel
• Family trips
• Luxury travel
• Budget backpacking
• Cultural experiences
• Adventure activities

Screenshots

Blog Listing	Category Filter
Paginated post cards	Filter by travel category

Blog Post	Rich Content
Full article view	Formatted text and images

Blog Editor
Lexical rich text editor

Not Found

Route: * (catch-all)

A custom 404 page is displayed when users navigate to a route that does not exist. The page provides a friendly message and links back to the homepage and other main sections of the site, helping users recover from navigation errors gracefully.

Screenshots

404 Page
Page not found with navigation options

Administrative Pages

The admin section is protected and requires administrator credentials to access. It provides comprehensive tools for managing all aspects of the platform.

Admin Login

Route: /admin/login

The administrative login page is separate from the public user login to maintain security isolation. It accepts the admin email and password configured in the application settings. Successful authentication creates an admin session cookie that grants access to all administrative features. Failed login attempts are logged for security monitoring.

Screenshots

Admin Login	Login Error
Administrator authentication	Invalid credentials handling

Admin Dashboard

Route: /admin

The main dashboard provides a centralized overview of platform statistics, analytics, and recent activity. Key performance metrics are displayed prominently, including total registered users, active bookings, published blog posts, and revenue summaries.

Analytics and Metrics:

• Visitor traffic statistics
• User registration trends
• Booking volume and revenue charts
• Blog engagement metrics
• Active user sessions

Charts built with Recharts visualize trends over time, helping administrators identify patterns and make data-driven decisions. Quick action buttons provide shortcuts to common administrative tasks such as approving pending bookings or reviewing new user registrations. Recent activity feeds show the latest user actions and system events.

Screenshots

Dashboard Overview
Main admin interface

User Management

Route: /admin/users

The user management page displays a searchable, paginated table of all registered users. The search functionality allows administrators to find users by name, email, or other attributes. Pagination controls handle large user bases efficiently.

Management Capabilities:

• View detailed user profiles
• Edit user information
• Toggle account active/inactive status
• Delete user accounts
• View registration dates and last login times
• Monitor user activity patterns

Administrators can activate or deactivate accounts as needed for moderation purposes. The interface provides clear visual indicators of account status and important dates.

Screenshots

User List
Paginated user table

Booking Management

Route: /admin/bookings

This page provides complete visibility into all bookings made through the platform. The booking list can be filtered by status categories: pending (awaiting confirmation), confirmed (approved and scheduled), cancelled (user or admin cancelled), and completed (past bookings).

Management Features:

• Search bookings by customer name or email
• Filter by booking status
• View detailed booking information
• Update booking status
• Track revenue by period
• Export booking data

Administrators can view comprehensive details for each booking including customer information, itemized services, payment status, and timeline. Status updates trigger notification emails to customers, keeping them informed of any changes.

Screenshots

Booking List
All bookings overview

Blog Management

Route: /admin/blog

The blog management interface provides administrative control over all blog content. The page lists all posts regardless of publication status, giving administrators visibility into both published articles and pending drafts.

Management Capabilities:

• View all posts (published and drafts)
• Edit existing content
• Toggle publication status
• Delete posts
• Review content before publication
• Monitor blog statistics

Statistics display engagement metrics for blog content, helping administrators understand which topics resonate with readers. Content moderation tools ensure quality and appropriateness of community contributions.

Screenshots

Post List
All posts overview

Search and Filtering

The application provides comprehensive search and filtering capabilities throughout the platform. A global search bar in the navigation allows users to find destinations and blog articles from any page.

Search Features:

• Destination search by name or keyword
• Blog article search by title or content
• Real-time search suggestions

Advanced Filters:

• Price range sliders
• User rating thresholds
• Seasonal availability (best time to visit)
• Activity type categorization
• Continent and region selection

Filters can be combined to narrow results precisely. Filter selections are preserved during navigation, allowing users to refine their search incrementally.

Screenshots

Filter Panel	Search Results
Continent, activity, and budget filters	Filtered destination results

Core Features

Responsive Design and Styling

The entire application is built with a visually appealing and user-friendly layout designed to enhance the user experience. High-quality images showcase destinations and create visual appeal throughout the site. Clear typography using modern font stacks ensures readability across all devices.

Responsive design principles implemented with Tailwind CSS ensure the interface adapts seamlessly to different screen sizes. On mobile devices, navigation collapses into an accessible hamburger menu, images resize appropriately, and layouts stack vertically for comfortable scrolling. Tablet and desktop views utilize available screen space with multi-column layouts and expanded navigation.

Intuitive navigation patterns guide users through the site logically. Consistent visual hierarchy helps users understand page structure and find information quickly. Interactive elements provide clear feedback through hover states, focus indicators, and transition animations powered by Framer Motion.

Screenshots

Desktop Layout	Mobile Layout
Full desktop experience	Mobile-optimized view

Mobile Navigation	Tablet View
Hamburger menu expanded	Tablet layout

Error Handling

“Ensure smooth user experiences by providing meaningful error messages.”

The application implements comprehensive error handling to maintain a smooth user experience even when issues occur. Payment failures display clear messages explaining the issue and suggesting resolution steps. Unavailable services are communicated with helpful alternatives when possible.

Network errors are caught and displayed with retry options. Form validation errors appear inline next to the relevant fields with specific guidance on how to correct the input. Server errors are logged for debugging while users see friendly messages that avoid technical jargon.

Toast notifications provide non-intrusive feedback for both successful actions and error conditions. The notification system uses the Sonner library to display consistent, accessible messages that automatically dismiss after an appropriate duration.

For detailed information about error handling implementation, see Error Handling.

Analytics Integration

The application integrates PostHog analytics to track user behavior and optimize the platform experience. Analytics capture page views, feature usage patterns, and conversion metrics while respecting user privacy.

Tracked Metrics:

• Page view counts and user flows
• Feature engagement (planner usage, blog reads)
• Booking funnel conversion rates
• Search and filter usage patterns
• Error occurrence frequency

Analytics data informs decisions about content prioritization, feature development, and user experience improvements. The integration is configured to comply with privacy requirements and can be adjusted based on user consent preferences.

Screenshots

Page Analytics
Page view tracking

Real-time Form Validation

Forms throughout the application provide immediate feedback using react-hook-form integrated with Zod validation schemas. Users see validation errors as they type, helping them correct issues before submission. This client-side validation reduces server load and improves the user experience by providing instant feedback.

Validation rules enforce data quality requirements including email format verification, password strength requirements, required field completion, and logical constraints such as departure dates preceding return dates.

Architecture

This document provides an overview of the MyTravel application’s code structure and organization. The project follows a modern full-stack architecture with a clear separation between the frontend React application and the backend ASP.NET Core API.

High-Level Architecture

The application consists of two main components that communicate over HTTP. The frontend handles all user interface concerns while the backend manages data persistence, business logic, and authentication.

Request Flow

When a user interacts with the application, requests flow through several layers before reaching the database. This diagram illustrates the typical request lifecycle.

Frontend Architecture

The frontend is built with React and TypeScript, using Vite as the build tool. The codebase follows a feature-based organization pattern with clear separation of concerns.

Frontend Directory Structure

mytravel.client/
├── client/
│   ├── index.html                 # HTML entry point
│   ├── public/                    # Static assets (images, fonts)
│   └── src/
│       ├── App.tsx                # Root component with routing
│       ├── main.tsx               # React entry point
│       ├── index.css              # Global styles (Tailwind)
│       │
│       ├── components/            # Reusable components
│       │   ├── admin/             # Admin-specific components
│       │   │   ├── admin-layout.tsx
│       │   │   ├── protected-admin-route.tsx
│       │   │   └── ...
│       │   ├── blocks/            # Content block components
│       │   ├── editor/            # Lexical editor components
│       │   ├── ui/                # Base UI components (55+)
│       │   │   ├── button.tsx
│       │   │   ├── card.tsx
│       │   │   ├── dialog.tsx
│       │   │   └── ...
│       │   ├── booking-form.tsx
│       │   ├── cart-sheet.tsx
│       │   ├── destination-card.tsx
│       │   ├── hero.tsx
│       │   ├── itinerary-planner.tsx
│       │   ├── layout.tsx
│       │   └── trip-summary.tsx
│       │
│       ├── context/               # React context providers
│       │   ├── blog-context.tsx   # Blog state management
│       │   └── cart-context.tsx   # Shopping cart state
│       │
│       ├── hooks/                 # Custom React hooks
│       │   ├── use-admin-auth.tsx # Admin authentication
│       │   ├── use-auth.tsx       # User authentication
│       │   ├── use-mobile.tsx     # Responsive detection
│       │   ├── use-ping.tsx       # Activity tracking
│       │   └── use-toast.ts       # Toast notifications
│       │
│       ├── lib/                   # Utilities and data
│       │   ├── data.ts            # API client functions
│       │   ├── destinations.ts    # Destination data
│       │   ├── mock-data.ts       # Development mock data
│       │   ├── queryClient.ts     # TanStack Query config
│       │   └── utils.ts           # Helper functions
│       │
│       └── pages/                 # Page components
│           ├── admin/             # Admin pages
│           │   ├── admin-blog.tsx
│           │   ├── admin-bookings.tsx
│           │   ├── admin-dashboard.tsx
│           │   ├── admin-login.tsx
│           │   └── admin-users.tsx
│           ├── blog.tsx
│           ├── blog-detail.tsx
│           ├── blog-editor.tsx
│           ├── booking.tsx
│           ├── checkout.tsx
│           ├── destination-details.tsx
│           ├── destinations.tsx
│           ├── home.tsx
│           ├── login.tsx
│           ├── not-found.tsx
│           └── planner.tsx
│
├── attached_assets/               # Generated images
├── components.json                # shadcn/ui configuration
├── eslint.config.js               # ESLint configuration
├── package.json                   # Dependencies and scripts
├── postcss.config.js              # PostCSS configuration
├── tailwind.config.js             # Tailwind CSS configuration
├── tsconfig.json                  # TypeScript configuration
└── vite.config.ts                 # Vite build configuration

Component Hierarchy

This diagram shows the relationship between major frontend components and how they compose to form the user interface.

Backend Architecture

The backend is built with ASP.NET Core using a minimal API approach. It follows a layered architecture with clear separation between endpoints, data access, and business logic.

Backend Directory Structure

MyTravel.Server/
├── Program.cs                     # Application entry point
│                                  # - Service configuration
│                                  # - Middleware pipeline
│                                  # - Endpoint registration
│
├── Data/                          # Data access layer
│   ├── ApplicationDbContext.cs    # EF Core context
│   │                              # - DbSet definitions
│   │                              # - Entity configurations
│   │                              # - Model definitions
│   └── DbSeeder.cs                # Database seeding
│                                  # - Sample destinations
│                                  # - Demo blog posts
│                                  # - Admin user creation
│
├── DTOs/                          # Data Transfer Objects
│   ├── BlogDtos.cs                # Blog request/response models
│   ├── BookingDtos.cs             # Booking request/response models
│   ├── UserDtos.cs                # User request/response models
│   └── WeatherForecast.cs         # Sample DTO
│
├── Endpoints/                     # API endpoint definitions
│   ├── ActivityEndpoints.cs       # Ping and heartbeat tracking
│   ├── AdminBlogEndpoints.cs      # Admin blog CRUD operations
│   ├── AdminBookingEndpoints.cs   # Admin booking management
│   ├── AdminEndpoints.cs          # Admin auth and user management
│   ├── BlogEndpoints.cs           # Public blog endpoints
│   ├── BookingEndpoints.cs        # Public booking endpoints
│   ├── UserEndpoints.cs           # User profile endpoints
│   └── WeatherEndpoints.cs        # Sample weather endpoint
│
├── Services/                      # Business logic services
│   ├── CustomSignInManager.cs     # Extended sign-in logic
│   └── EmailSender.cs             # Email sending service
│
├── Properties/
│   └── launchSettings.json        # Development launch profiles
│
├── Views/                         # Server-side views (if any)
│   └── PageBlockTypes/
│
├── wwwroot/                       # Static file serving
│
├── appsettings.json               # Base configuration
├── appsettings.Development.json   # Development configuration
├── MyTravel.Server.csproj         # Project file
└── MyTravel.Server.http           # HTTP request testing

API Endpoint Organization

The API endpoints are organized into logical groups using ASP.NET Core’s minimal API pattern with extension methods.

Data Model

The application uses Entity Framework Core with SQLite for data persistence. The data model centers around users, bookings, and blog content.

Authentication Flow

The application implements two separate authentication flows: one for regular users and one for administrators.

User Authentication

Admin Authentication

State Management

The frontend uses a combination of React Context and TanStack Query for state management. Local UI state is managed with React hooks, while server state is cached and synchronized using TanStack Query.

Build and Deployment

The application uses different build configurations for development and production environments.

Development Mode

In development, the Vite development server runs on port 49764 and proxies API requests to the ASP.NET Core server on port 5083. The SPA Proxy middleware automatically starts the Vite server when the .NET application launches.

Production Mode

For production, Vite builds optimized static assets that are served from the ASP.NET Core wwwroot directory. The .NET application serves both the API and the static frontend files.

Technologies

This document provides a comprehensive overview of the libraries, frameworks, and tools used in the MyTravel application. The project leverages modern technologies for both frontend and backend development to deliver a robust and maintainable codebase.

Technology Stack Overview

Frontend Technologies

The frontend is built with React and TypeScript, utilizing a modern toolchain for development and production builds.

Core Framework

Build Tools

Styling

Routing

State Management and Data Fetching

UI Components

The application uses Radix UI primitives as the foundation for accessible, unstyled UI components. These are styled with Tailwind CSS to match the application design.

Forms and Validation

Rich Text Editor

Maps and Geolocation

Drag and Drop

Animations

Charts and Data Visualization

Date and Time

Icons

Notifications

Analytics

Utilities

Backend Technologies

The backend is built on ASP.NET Core with Entity Framework Core for data access.

Core Framework

Authentication and Authorization

Data Access

API Documentation

Development Tools

Development Environment

Recommended Tools

Browser Support

The application targets modern browsers with ES2020+ support:

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

Development Dependencies

Error Handling

This document explains the error handling strategies implemented throughout the MyTravel application. Comprehensive error handling ensures users receive meaningful feedback when issues occur, maintaining a smooth experience even during failures.

Error Handling Philosophy

“Ensure smooth user experiences by providing meaningful error messages.”

The application follows these core principles for error handling:

1. User-Friendly Messages - Technical errors are translated into understandable language
2. Graceful Degradation - The application remains functional even when individual features fail
3. Appropriate Feedback - Users receive timely notifications about the success or failure of their actions
4. Logging for Debugging - Errors are captured for developer troubleshooting without exposing sensitive details to users

Error Flow Architecture

Frontend Error Handling

API Request Helper

The application uses a centralized API request function that standardizes error handling for all HTTP requests. This is implemented in lib/queryClient.ts.

async function throwIfResNotOk(res: Response) {
  if (!res.ok) {
    const text = (await res.text()) || res.statusText;
    throw new Error(`${res.status}: ${text}`);
  }
}

export async function apiRequest(
  method: string,
  url: string,
  data?: unknown | undefined,
): Promise<Response> {
  const res = await fetch(url, {
    method,
    headers: data ? { "Content-Type": "application/json" } : {},
    body: data ? JSON.stringify(data) : undefined,
    credentials: "include",
  });

  await throwIfResNotOk(res);
  return res;
}

This helper function:

• Checks if the response status indicates an error (!res.ok)
• Extracts the error message from the response body or uses the status text
• Throws an Error with both the status code and message for handling upstream

TanStack Query Error Handling

TanStack Query is configured with custom error handling behavior in queryClient.ts:

type UnauthorizedBehavior = "returnNull" | "throw";

export const getQueryFn: <T>(options: {
  on401: UnauthorizedBehavior;
}) => QueryFunction<T> =
  ({ on401: unauthorizedBehavior }) =>
  async ({ queryKey }) => {
    const res = await fetch(queryKey.join("/") as string, {
      credentials: "include",
    });

    if (unauthorizedBehavior === "returnNull" && res.status === 401) {
      return null;
    }

    await throwIfResNotOk(res);
    return await res.json();
  };

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryFn: getQueryFn({ on401: "throw" }),
      refetchInterval: false,
      refetchOnWindowFocus: false,
      staleTime: Infinity,
      retry: false,
    },
    mutations: {
      retry: false,
    },
  },
});

Key configuration choices:

• 401 Handling - Configurable behavior for unauthorized responses (return null or throw)
• No Automatic Retry - Failed requests are not automatically retried to prevent redundant server load
• No Refetch on Focus - Prevents unexpected data refreshes when switching browser tabs

Mutation Error Handling Pattern

When performing mutations (create, update, delete operations), errors are handled in the onError callback:

const mutation = useMutation({
  mutationFn: async (data: FormData) => {
    const response = await apiRequest("POST", "/api/bookings", data);
    return response.json();
  },
  onSuccess: (data) => {
    toast({
      title: "Success",
      description: "Your booking has been confirmed!",
    });
    // Navigate or update UI
  },
  onError: (error: Error) => {
    toast({
      title: "Booking Failed",
      description: error.message || "Unable to complete your booking. Please try again.",
      variant: "destructive",
    });
  },
});

Toast Notification System

The application uses a toast notification system (Sonner/Radix Toast) for user feedback. Toasts support multiple variants for different message types.

Toast Usage Examples:

// Success notification
toast({
  title: "Profile Updated",
  description: "Your changes have been saved successfully.",
});

// Error notification
toast({
  title: "Error",
  description: "Failed to save changes. Please try again.",
  variant: "destructive",
});

// Informational notification
toast({
  title: "Session Expiring",
  description: "Your session will expire in 5 minutes.",
});

Form Validation with Zod

Forms use react-hook-form with Zod schemas for client-side validation. This catches errors before they reach the server.

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { z } from "zod";

const loginSchema = z.object({
  email: z.string().email("Please enter a valid email address"),
  password: z.string().min(6, "Password must be at least 6 characters"),
});

type LoginForm = z.infer<typeof loginSchema>;

function LoginPage() {
  const form = useForm<LoginForm>({
    resolver: zodResolver(loginSchema),
    defaultValues: {
      email: "",
      password: "",
    },
  });

  const onSubmit = async (data: LoginForm) => {
    try {
      await apiRequest("POST", "/api/login", data);
      // Handle success
    } catch (error) {
      form.setError("root", {
        message: "Invalid email or password",
      });
    }
  };

  return (
    <Form {...form}>
      <FormField
        control={form.control}
        name="email"
        render={({ field }) => (
          <FormItem>
            <FormLabel>Email</FormLabel>
            <FormControl>
              <Input {...field} />
            </FormControl>
            <FormMessage /> {/* Displays validation errors */}
          </FormItem>
        )}
      />
      {/* ... */}
    </Form>
  );
}

Validation Error Display:

404 Not Found Page

The application includes a custom 404 page for handling invalid routes:

// pages/not-found.tsx
export default function NotFound() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h1 className="text-6xl font-bold text-gray-900">404</h1>
      <p className="text-xl text-gray-600 mt-4">Page not found</p>
      <p className="text-gray-500 mt-2">
        The page you're looking for doesn't exist or has been moved.
      </p>
      <Link href="/" className="mt-6">
        <Button>Return to Homepage</Button>
      </Link>
    </div>
  );
}

Backend Error Handling

Standardized Error Responses

The backend uses ASP.NET Core’s Results class to return consistent error responses:

Error Response Examples:

// 400 Bad Request - Validation errors
if (string.IsNullOrWhiteSpace(request.Title))
{
    return Results.BadRequest(new { message = "Title is required" });
}

if (request.Items == null || request.Items.Count == 0)
{
    return Results.BadRequest(new { message = "At least one booking item is required" });
}

// 401 Unauthorized - Authentication required
var adminCookie = httpContext.Request.Cookies["admin_session"];
if (adminCookie != "authenticated")
{
    return Results.Unauthorized();
}

// 403 Forbidden - Access denied
if (booking.UserId != null && booking.UserId != userId)
{
    return Results.Forbid();
}

// 404 Not Found - Resource doesn't exist
var post = await db.BlogPosts.FindAsync(id);
if (post == null)
{
    return Results.NotFound(new { message = "Blog post not found" });
}

Input Validation

All API endpoints validate input before processing:

// Booking endpoint validation
app.MapPost("/api/bookings", async (CreateBookingRequest request, ...) =>
{
    // Validate required items
    if (request.Items == null || request.Items.Count == 0)
    {
        return Results.BadRequest(new { message = "At least one booking item is required" });
    }

    // Validate guest checkout requirements
    if (user.Identity?.IsAuthenticated != true)
    {
        if (string.IsNullOrWhiteSpace(request.CustomerEmail) || 
            string.IsNullOrWhiteSpace(request.CustomerName))
        {
            return Results.BadRequest(new { 
                message = "Customer email and name are required for guest checkout" 
            });
        }
    }

    // Validate enum values
    if (!Enum.TryParse<BookingStatus>(request.Status, true, out var statusEnum))
    {
        return Results.BadRequest(new { message = "Invalid status value" });
    }

    // ... proceed with valid request
});

Non-Critical Operation Error Handling

For operations that shouldn’t block the main request (like sending emails), errors are caught and logged but don’t fail the overall operation:

// Create booking
db.Bookings.Add(booking);
await db.SaveChangesAsync();

// Try to send confirmation email (non-critical)
try
{
    await emailSender.SendConfirmationLinkAsync(
        new ApplicationUser { Email = booking.CustomerEmail },
        booking.CustomerEmail,
        emailBody);
}
catch
{
    // Email sending failed, but booking was created successfully
    // Log the error for investigation but don't fail the request
}

// Return success - booking was created
return Results.Created($"/api/bookings/{booking.Id}", new
{
    id = booking.Id,
    message = "Booking created successfully"
});

Authentication Error Handling

The admin authentication system validates credentials against configuration:

app.MapPost("/api/admin/login", async (
    AdminLoginRequest request,
    IConfiguration config,
    HttpContext httpContext) =>
{
    var adminEmail = config["AdminCredentials:Email"];
    var adminPassword = config["AdminCredentials:Password"];

    if (request.Email == adminEmail && request.Password == adminPassword)
    {
        // Set secure cookie and return success
        httpContext.Response.Cookies.Append("admin_session", "authenticated", 
            new CookieOptions
            {
                HttpOnly = true,
                Secure = true,
                SameSite = SameSiteMode.Strict,
                Expires = DateTimeOffset.UtcNow.AddHours(8)
            });

        return Results.Ok(new { message = "Admin login successful", isAdmin = true });
    }

    // Invalid credentials - return 401 without revealing which field was wrong
    return Results.Unauthorized();
});

Database Error Handling

Entity Framework operations are wrapped in appropriate error handling:

// Delete user with Identity Manager (handles cascading constraints)
var result = await userManager.DeleteAsync(user);
if (!result.Succeeded)
{
    return Results.BadRequest(new { 
        message = "Failed to delete user", 
        errors = result.Errors 
    });
}

return Results.Ok(new { message = "User deleted successfully" });

Error Scenarios and User Experience

Common Error Scenarios

Error Recovery Patterns

Best Practices Summary

Frontend

1. Always handle errors in mutations - Use onError callbacks to display user feedback
2. Validate before submitting - Use Zod schemas with react-hook-form
3. Provide specific messages - Tell users what went wrong and how to fix it
4. Use appropriate toast variants - destructive for errors, default for success
5. Handle loading states - Show spinners/skeletons during async operations

Backend

1. Return appropriate status codes - 400 for validation, 401 for auth, 404 for missing resources
2. Include helpful messages - Explain what went wrong in the response body
3. Don’t expose sensitive information - Avoid revealing system internals in error messages
4. Handle non-critical failures gracefully - Don’t fail the whole request if email sending fails
5. Validate all input - Never trust client-side validation alone